(cd src/doc &&
bundle &&
bundle exec middleman build) &&
- echo crates.io >> src/doc/build/CNAME &&
- sudo pip install ghp-import
+ sudo pip install ghp-import &&
ghp-import -n src/doc/build &&
git push -f https://${TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages
env:
```
This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your project.
+needs to compile your project.
Here's what's in `src/main.rs`:
This will get you the latest Rust nightly for your platform along with
the latest Cargo. You should run this script almost every day to get the latest updates.
-
+
If you are on Windows, you can directly download the latest [Rust](http://static.rust-lang.org/dist/rust-nightly-install.exe)
-and [Cargo](http://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-mingw32.tar.gz) nightlies.
+and [Cargo](http://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-mingw32.tar.gz) nightlies.
Alternatively, you can build Cargo from source.
To start a new project with Cargo, use `cargo new`:
```shell
-$ cargo new hello_world --bin
+$ cargo new hello_world --bin --git
```
We're passing `--bin` because we're making a binary program: if we
-were making a library, we'd leave it off.
+were making a library, we'd leave it off. We also pass `--git` to auto-generate
+a `.gitignore` and set up the git repository, but nothing will be committed.
Let's check out what Cargo has generated for us:
```
This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your project.
+needs to compile your project.
Here's what's in `src/main.rs`:
You can specify a script that Cargo should execute before invoking
`rustc`. You can use this to compile C code that you will [link][1] into
-your Rust code, for example.
+your Rust code, for example. More information can be found in the building
+non-rust code [guide][2]
[1]: http://doc.rust-lang.org/rust.html#external-blocks
+[2]: native-build.html
```toml
[package]
build = "make"
```
+```toml
+[package]
+# ...
+
+# Specify two commands to be run sequentially
+build = ["./configure", "make"]
+```
+
+## The `exclude` Field (optional)
+
+You can explicitly specify to Cargo that a set of globs should be ignored for
+the purposes of packaging and rebuilding a package. The globs specified in this
+field identify a set of files that are not included when a package is published
+as well as ignored for the purposes of detecting when to rebuild a package.
+
+If a VCS is being used for a package, the `exclude` field will be seeded with
+the VCS's ignore settings (`.gitignore` for git for example).
+
+```toml
+[package]
+# ...
+exclude = ["build/**/*.o", "doc/**/*.html"]
+```
+
# The `[dependencies.*]` Sections
You list dependencies using `[dependencies.<name>]`. For example, if you
Soon, you will be able to load packages from the Cargo registry as well.
+# The `[dev-dependencies.*]` Sections
+
+The format of this section is equivalent to `[dependencies.*]`. Dev-dependencies
+are not used when compiling a package for building, but are used for compiling
+tests and benchmarks.
+
+These dependencies are *not* propagated to other packages which depend on this
+package.
+
# The Project Layout
If your project is an executable, name the main source file `src/main.rs`.
*.rs
▾ tests/ # (optional) integration tests
*.rs
+▾ benches/ # (optional) benchmarks
+ *.rs
```
# Examples
<library-name>` like any other code that depends on it.
* Compile your library's examples.
-# Building Dynamic Libraries
+# Configuring a target
+
+Both `[[bin]]` and `[lib]` sections support similar configuration for specifying
+how a target should be built. The example below uses `[lib]`, but it also
+applies to all `[[bin]]` sections as well. All values listed ar the defaults for
+that option unless otherwise specified.
+
+```toml
+[package]
+# ...
+
+[lib]
+
+# The name of a target is the name of the library that will be generated. This
+# is defaulted to the name of the package or project.
+name = "foo"
+
+# This field points at where the crate is located, relative to the Cargo.toml.
+path = "src/lib.rs"
+
+# A flag for enabling unit tests for this target. This is used by `cargo test`.
+test = true
+
+# A flag for enabling documentation tests for this target. This is only
+# relevant for libraries, it has no effect on [[bin]] sections. This is used by
+# `cargo test`.
+doctest = true
+
+# A flag for enabling benchmarks for this target. This is used by `cargo bench`.
+bench = true
+
+# A flag for enabling documentation of this target. This is used by `cargo doc`.
+doc = true
+
+# If the target is meant to be a compiler plugin, this field must be set to true
+# for cargo to correctly compile it and make it available for all dependencies.
+plugin = false
+```
+
+# Building Dynamic or Static Libraries
If your project produces a library, you can specify which kind of
library to build by explicitly listing the library in your `Cargo.toml`:
```toml
# ...
-[[lib]]
+[lib]
name = "..."
-crate-types = [ "dylib" ]
+# this could be "staticlib" as well
+crate-type = ["dylib"]
```
-The available options are `dylib` and `rlib`. You should only use
-this option in a project. Cargo will always compile **packages**
-(dependencies) based on the requirements of the project that includes
-them.
+The available options are `dylib`, `rlib`, and `staticlib`. You should only use
+this option in a project. Cargo will always compile **packages** (dependencies)
+based on the requirements of the project that includes them.
directory.
* The actual location of `$OUT_DIR` is
`/path/to/project/target/native/$your-out-dir`.
+* The target triple that the build command should compile for is specified by
+ the `TARGET` environment variable.
What this means is that the normal workflow for build dependencies is:
into the provided `$OUT_DIR`.
* The next time a user runs `cargo build`, if the dependency has not
changed (via `cargo update <your-package>`), Cargo will reuse the
- output you provided before.
+ output you provided before. Your build command will not be invoked.
* If the user updates your package to a new version (or git revision),
- Cargo will wipe the old `$OUT_DIR` and re-invoke your build script.
+ Cargo will **not** remove the old `$OUT_DIR` will re-invoke your build script.
+ Your build script is responsible for bringing the state of the old directory
+ up to date with the current state of the input files.
In general, build scripts may not be as portable as we'd like today. We
encourage package authors to write build scripts that can work in both
packages. We intend for it to eventually serve this purpose for Cargo
projects.
-[1]: http://doc.rust-lang.org/rust.html#runtime-services,-linkage-and-debugging
+[1]: http://doc.rust-lang.org/rust.html#linkage
[2]: https://github.com/alexcrichton/link-config
+
+# A complete example
+
+The code blocks below lay out a cargo project which has a small and simple C
+dependency along with the necessary infrastructure for linking that to the rust
+program.
+
+```toml
+# Cargo.toml
+[package]
+
+name = "hello-world-from-c"
+version = "0.1.0"
+authors = [ "wycats@gmail.com" ]
+build = "make -C build"
+```
+
+```make
+# build/Makefile
+
+# Support cross compilation to/from 32/64 bit.
+ARCH := $(word 1, $(subst -, ,$(TARGET)))
+ifeq ($(ARCH),i686)
+CFLAGS += -m32 -fPIC
+else
+CFLAGS += -m64 -fPIC
+endif
+
+all:
+ $(CC) $(CFLAGS) hello.c -c -o $(OUT_DIR)/hello.o
+ $(AR) crus $(OUT_DIR)/libhello.a $(OUT_DIR)/hello.o
+
+```
+
+```c
+// build/hello.c
+int foo() { return 1; }
+```
+
+```rust
+// src/main.rs
+
+#[link(name = "hello", kind = "static")]
+extern {
+ fn foo() -> i32;
+}
+
+fn main() {
+ let number = unsafe { foo() };
+ println!("found {} from C!", number);
+}
+```
projects / cargo.git / commitdiff